OAuth 2.0 для мобильных и настольных приложений

Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.

В этом документе объясняется, как приложения, установленные на таких устройствах, как телефоны, планшеты и компьютеры, используют конечные точки Google OAuth 2.0 для авторизации доступа к API данных YouTube.

OAuth 2.0 позволяет пользователям делиться определенными данными с приложением, сохраняя при этом свои имена пользователей, пароли и другую информацию конфиденциальной. Например, приложение может использовать OAuth 2.0 для получения разрешения на загрузку видео на канал пользователя YouTube.

Установленные приложения распространяются на отдельные устройства, и предполагается, что эти приложения не могут хранить секреты. Они могут получать доступ к API Google, пока пользователь присутствует в приложении или когда приложение работает в фоновом режиме.

Этот поток авторизации аналогичен потоку, используемому для приложений веб-сервера . Главное отличие состоит в том, что установленные приложения должны открывать системный браузер и предоставлять локальный URI перенаправления для обработки ответов от сервера авторизации Google.

Альтернативы

Для мобильных приложений вы можете предпочесть Google Sign-in для Android или iOS . Клиентские библиотеки Google Sign-in обрабатывают аутентификацию и авторизацию пользователей, и их может быть проще реализовать, чем описанный здесь протокол более низкого уровня.

Для приложений, работающих на устройствах, которые не поддерживают системный браузер или имеют ограниченные возможности ввода, таких как телевизоры, игровые консоли, камеры или принтеры, см. OAuth 2.0 для телевизоров и устройств или Вход на телевизорах и устройствах с ограниченными возможностями ввода .

Библиотеки и образцы

Мы рекомендуем следующие библиотеки и примеры, которые помогут вам реализовать процесс OAuth 2.0, описанный в этом документе:

• Библиотека AppAuth для Android
• Библиотека AppAuth для iOS
• OAuth для приложений: примеры Windows

Предпосылки

Включите API для вашего проекта

Любое приложение, которое вызывает API Google, должно включить эти API в API Console.

Чтобы включить API для вашего проекта:

1. Open the API Library в Google API Console.
2. If prompted, select a project, or create a new one.
3. Используйте страницу библиотеки , чтобы найти и включить API данных YouTube. Найдите любые другие API, которые будет использовать ваше приложение, и включите их тоже.

Создать учетные данные для авторизации

Любое приложение, использующее OAuth 2.0 для доступа к API Google, должно иметь учетные данные авторизации, которые идентифицируют приложение на сервере OAuth 2.0 Google. Следующие шаги объясняют, как создать учетные данные для вашего проекта. Затем ваши приложения могут использовать учетные данные для доступа к API, которые вы включили для этого проекта.

1. Go to the Credentials page.
2. Нажмите Создать клиента .
3. В следующих разделах описываются типы клиентов, которые поддерживает сервер авторизации Google. Выберите тип клиента, рекомендуемый для вашего приложения, назовите своего клиента OAuth и задайте другие поля в форме соответствующим образом.

Определить области доступа

Области действия позволяют вашему приложению запрашивать доступ только к тем ресурсам, которые ему нужны, а также позволяют пользователям контролировать объем доступа, который они предоставляют вашему приложению. Таким образом, может существовать обратная зависимость между количеством запрошенных областей действия и вероятностью получения согласия пользователя.

Прежде чем приступить к реализации авторизации OAuth 2.0, мы рекомендуем вам определить области, для доступа к которым вашему приложению потребуется разрешение.

API данных YouTube v3 использует следующие области действия:

Документ «Области действия API OAuth 2.0» содержит полный список областей действия, которые можно использовать для доступа к API Google.

Получение токенов доступа OAuth 2.0

Следующие шаги показывают, как ваше приложение взаимодействует с сервером OAuth 2.0 Google для получения согласия пользователя на выполнение запроса API от имени пользователя. Ваше приложение должно иметь это согласие, прежде чем оно сможет выполнить запрос API Google, требующий авторизации пользователя.

Шаг 1: Создайте верификатор кода и вызов

Google поддерживает протокол Proof Key for Code Exchange (PKCE), чтобы сделать поток установленного приложения более безопасным. Для каждого запроса авторизации создается уникальный верификатор кода, а его преобразованное значение, называемое «code_challenge», отправляется на сервер авторизации для получения кода авторизации.

Создать верификатор кода

code_verifier — это высокоэнтропийная криптографическая случайная строка, использующая незарезервированные символы [AZ] / [az] / [0-9] / "-" / "." / "_" / "~", с минимальной длиной 43 символа и максимальной длиной 128 символов.

Верификатор кода должен обладать достаточной энтропией, чтобы сделать угадывание значения нецелесообразным.

Создайте кодовое задание

Поддерживаются два метода создания задания по коду.

code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))

code_challenge = code_verifier

Шаг 2: Отправьте запрос на сервер Google OAuth 2.0

Чтобы получить авторизацию пользователя, отправьте запрос на сервер авторизации Google по адресу https://accounts.google.com/o/oauth2/v2/auth . Эта конечная точка обрабатывает поиск активного сеанса, аутентифицирует пользователя и получает его согласие. Конечная точка доступна только через SSL и отклоняет HTTP-соединения (не SSL).

Сервер авторизации поддерживает следующие параметры строки запроса для установленных приложений:

Примеры URL-адресов авторизации

На вкладках ниже показаны примеры URL-адресов авторизации для различных вариантов URI перенаправления.

URL-адреса идентичны, за исключением значения параметра redirect_uri . URL-адреса также содержат обязательные параметры response_type и client_id , а также необязательный параметр state . Каждый URL-адрес содержит разрывы строк и пробелы для удобства чтения.

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.readonly&
 response_type=code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&
 redirect_uri=com.example.app%3A/oauth2redirect&
 client_id=client_id

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.readonly&
 response_type=code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&
 redirect_uri=http%3A//127.0.0.1%3A9004&
 client_id=client_id

Шаг 3: Google запрашивает у пользователя согласие

На этом этапе пользователь решает, предоставить ли вашему приложению запрошенный доступ. На этом этапе Google отображает окно согласия, в котором указано имя вашего приложения и службы API Google, для которых оно запрашивает разрешение на доступ с учетными данными пользователя и сводкой областей доступа, которые должны быть предоставлены. Затем пользователь может дать согласие на предоставление доступа к одной или нескольким областям, запрошенным вашим приложением, или отклонить запрос.

Вашему приложению не нужно ничего делать на этом этапе, поскольку оно ждет ответа от сервера Google OAuth 2.0, указывающего, был ли предоставлен какой-либо доступ. Этот ответ объясняется в следующем шаге.

Шаг 4: Обработка ответа сервера OAuth 2.0

Способ, которым ваше приложение получает ответ авторизации, зависит от схемы перенаправления URI , которую оно использует. Независимо от схемы, ответ будет содержать либо код авторизации ( code ), либо ошибку ( error ). Например, error=access_denied указывает на то, что пользователь отклонил запрос.

Если пользователь предоставляет доступ к вашему приложению, вы можете обменять код авторизации на токен доступа и токен обновления, как описано в следующем шаге.

Шаг 5: Обмен кода авторизации на токены обновления и доступа

Чтобы обменять код авторизации на токен доступа, вызовите конечную точку https://oauth2.googleapis.com/token и задайте следующие параметры:

В следующем фрагменте показан пример запроса:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&
client_id=your_client_id&
client_secret=your_client_secret&
redirect_uri=http://127.0.0.1:9004&
grant_type=authorization_code

Google отвечает на этот запрос, возвращая объект JSON, содержащий краткосрочный токен доступа и токен обновления.

Ответ содержит следующие поля:

В следующем фрагменте показан пример ответа:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "token_type": "Bearer",
  "scope": "https://www.googleapis.com/auth/youtube.force-ssl",
  "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

Шаг 6: Проверьте, какие области действия предоставили пользователи

При запросе нескольких разрешений (областей действия) пользователи могут не предоставить вашему приложению доступ ко всем из них. Ваше приложение должно проверять, какие области действия были фактически предоставлены, и корректно обрабатывать ситуации, когда некоторые разрешения отклоняются, обычно отключая функции, которые полагаются на эти отклоненные области действия.

Однако есть исключения. Приложения Google Workspace Enterprise с делегированием полномочий на весь домен или приложения, помеченные как Trusted , обходят экран согласия на детализированные разрешения. Для этих приложений пользователи не увидят экран согласия на детализированные разрешения. Вместо этого ваше приложение либо получит все запрошенные области, либо ни одной.

Более подробную информацию см. в разделе Как работать с детализированными разрешениями .

Чтобы проверить, предоставил ли пользователь вашему приложению доступ к определенной области, проверьте поле scope в ответе токена доступа. Области доступа, предоставленные access_token, выражены в виде списка разделенных пробелами, чувствительных к регистру строк.

Например, следующий пример ответа токена доступа указывает на то, что пользователь предоставил вашему приложению разрешение просматривать, редактировать и навсегда удалять видео, оценки, комментарии и субтитры пользователя на YouTube:

  {
    "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
    "expires_in": 3920,
    "token_type": "Bearer",
    "scope": "https://www.googleapis.com/auth/youtube.force-ssl",
    "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
  }

Вызов API Google

После того, как ваше приложение получит токен доступа, вы сможете использовать его для вызовов API Google от имени данной учетной записи пользователя, если область(ы) доступа, требуемые API, были предоставлены. Для этого включите токен доступа в запрос к API, включив либо параметр запроса access_token , либо значение заголовка HTTP Authorization Bearer . Когда это возможно, предпочтительнее использовать заголовок HTTP, поскольку строки запросов, как правило, видны в журналах сервера. В большинстве случаев вы можете использовать клиентскую библиотеку для настройки вызовов API Google (например, при вызове API данных YouTube ).

Обратите внимание, что API данных YouTube поддерживает учетные записи служб только для владельцев контента YouTube, которые владеют и управляют несколькими каналами YouTube, например, звукозаписывающими компаниями и киностудиями.

Вы можете опробовать все API Google и ознакомиться с их возможностями на OAuth 2.0 Playground .

Примеры HTTP GET

Вызов конечной точки youtube.channels (API данных YouTube) с использованием HTTP-заголовка Authorization: Bearer может выглядеть следующим образом. Обратите внимание, что вам необходимо указать собственный токен доступа:

GET /youtube/v3/channels?part=snippet&mine=true HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

Вот вызов того же API для аутентифицированного пользователя с использованием параметра строки запроса access_token :

GET https://www.googleapis.com/youtube/v3/channels?access_token=access_token&part=snippet&mine=true

примеры curl

Вы можете протестировать эти команды с помощью приложения командной строки curl . Вот пример, который использует опцию заголовка HTTP (предпочтительно):

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/v3/channels?part=snippet&mine=true

Или, в качестве альтернативы, параметр строки запроса:

curl https://www.googleapis.com/youtube/v3/channels?access_token=access_token&part=snippet&mine=true

Обновление токена доступа

Токены доступа периодически истекают и становятся недействительными учетными данными для соответствующего запроса API. Вы можете обновить токен доступа, не запрашивая у пользователя разрешения (в том числе, когда пользователь отсутствует), если вы запросили офлайн-доступ к областям, связанным с токеном.

Чтобы обновить токен доступа, ваше приложение отправляет HTTPS POST запрос на сервер авторизации Google ( https://oauth2.googleapis.com/token ), включающий следующие параметры:

В следующем фрагменте показан пример запроса:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

client_id=your_client_id&
client_secret=your_client_secret&
refresh_token=refresh_token&
grant_type=refresh_token

Пока пользователь не отменил доступ, предоставленный приложению, сервер токенов возвращает объект JSON, содержащий новый токен доступа. Следующий фрагмент показывает пример ответа:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly",
  "token_type": "Bearer"
}

Обратите внимание, что существуют ограничения на количество выдаваемых токенов обновления: одно ограничение на комбинацию клиент/пользователь и еще одно ограничение на пользователя по всем клиентам. Вам следует сохранять токены обновления в долгосрочном хранилище и продолжать использовать их, пока они остаются действительными. Если ваше приложение запрашивает слишком много токенов обновления, оно может столкнуться с этими ограничениями, и в этом случае старые токены обновления перестанут работать.

Отзыв токена

В некоторых случаях пользователь может захотеть отозвать доступ, предоставленный приложению. Пользователь может отозвать доступ, посетив Настройки учетной записи . Дополнительную информацию см. в разделе Удалить доступ к сайту или приложению в документе поддержки Сторонние сайты и приложения с доступом к вашей учетной записи .

Приложение также может программно отозвать предоставленный ему доступ. Программный отзыв важен в случаях, когда пользователь отписывается, удаляет приложение или ресурсы API, необходимые приложению, существенно изменились. Другими словами, часть процесса удаления может включать запрос API, чтобы гарантировать, что разрешения, ранее предоставленные приложению, будут удалены.

Чтобы программно отозвать токен, ваше приложение отправляет запрос на https://oauth2.googleapis.com/revoke и включает токен в качестве параметра:

curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
        https://oauth2.googleapis.com/revoke?token={token}

Токен может быть токеном доступа или токеном обновления. Если токен является токеном доступа и у него есть соответствующий токен обновления, токен обновления также будет отозван.

Если отзыв успешно обработан, то код статуса HTTP ответа равен 200 В случае возникновения ошибок возвращается код статуса HTTP 400 вместе с кодом ошибки.

Методы перенаправления приложений

Защитите свои приложения

Доступ по времени

Доступ на основе времени позволяет пользователю предоставить вашему приложению доступ к своим данным на ограниченный период времени для выполнения действия. Доступ на основе времени доступен в некоторых продуктах Google во время потока согласия, предоставляя пользователям возможность предоставить доступ на ограниченный период времени. Примером является API переносимости данных , который позволяет выполнять однократную передачу данных.

Когда пользователь предоставляет вашему приложению доступ на основе времени, токен обновления истекает по истечении указанного периода. Обратите внимание, что токены обновления могут быть аннулированы раньше при определенных обстоятельствах; см. эти случаи для получения подробной информации. Поле refresh_token_expires_in возвращаемое в ответе обмена кодом авторизации, представляет собой время, оставшееся до истечения срока действия токена обновления в таких случаях.

Дальнейшее чтение

В документе IETF Best Current Practice OAuth 2.0 для нативных приложений изложены многие из описанных здесь передовых практик.